When prev/next is clicked to the first/last page, that chevron is rebuilt as disabled (is-disabled + aria-disabled) but is still a focusable, still-visible <button>, so candidates.find(visible) parks focus right back on it — a control the user can no longer activate. Since the candidate list already falls through to .tb-pagination__page.is-current, would it be worth skipping disabled candidates here (e.g. filtering out .is-disabled) so boundary navigation lands focus on the current-page button instead of a dead chevron?

Link vs. interactive mode is selected implicitly by whether basePath happens to be passed. That's a meaningful behavioral fork — real anchors + SSR navigation vs. event-emitting buttons rebuilt by JS — hinging on one optional prop's presence, and it's easy to get subtly wrong from a call site: a consumer that means to be interactive but passes a basePath silently gets anchors and no events. Would an explicit mode: 'link' | 'interactive' prop (with basePath required only for link mode) make the contract more discoverable? The doc comment is good; it's just that the type signature itself doesn't express the coupling.

This prev/next chevron branch (link <a> / interactive <button> / disabled <span>) is written out four times in the template — prev and next, each duplicated across the --numbers list and the --compact row — differing only in direction, rel, label, and data-nav-role. A small local helper (a function returning the fragment, or an inline sub-component parameterised by direction/target/enabled) would collapse the four near-identical copies into one and keep the variants from drifting. Not load-bearing, but it's the densest part of the file to read.

These two path strings duplicate paths.left/paths.right in Chevron.astro. The comment honestly flags the coupling, but a comment won't keep them in sync — if the icon is ever redrawn, the runtime-built chevrons here drift from the build-time <Chevron> ones that Pagination.astro renders. Since Chevron.astro is essentially a thin wrapper over a path map, could that map be hoisted into a shared TS module that both Chevron.astro and this file import, rather than re-declaring the d-strings?

applyPageSizeToUi reaches into PerPageSelector's internal DOM contract — [data-per-page-option], [data-per-page-value], [data-per-page-label], and this tb-pagination__per-page-option--selected class — to reflect a restored ?pageSize= back into the dropdown. PerPageSelector already owns that markup and does the identical class/aria/label toggling in its own option-click handler, so the selection logic now lives in two places and a rename on either side silently breaks URL-restore here with no type safety to catch it. Could PerPageSelector expose a small imperative helper (e.g. setPerPageValue(root, n)) or react to a tb-pagination:set-page-size event so consumers don't hand-poke its internals? (It does mirror the existing applySortToUi/IotHubSort pattern, so it's at least locally consistent.)

Five of the six interactive consumers call updatePagination with hideOnSinglePage: true; this IoT Hub path omits it and instead leans on the SSR page.lastPage > 1 guard plus showFetchError toggling nav.hidden by hand. The effect differs: if a runtime filter narrows results to a single page here, the nav stays visible showing just "1" rather than hiding like the other surfaces. Intentional asymmetry, or just an omission? Either way, a one-line comment at this call site noting the deliberate divergence from the shared default would save the next person from "fixing" it to match.

These two path strings are a verbatim copy of the left/right entries in Chevron.astro's path map, and the comment right above ("Same geometry as Chevron.astro") spells out exactly the copy-paste invariant this PR is otherwise trying to eliminate. The SSR path already renders <Chevron> directly — only the runtime rebuild in pagination-client.ts needs the raw strings. Could the geometry come from a single source (e.g. Chevron.astro importing these paths, or both reading one shared constant), so a future tweak to the icon can't silently drift between the static and dynamic renders?

Every other user-facing string here is either centralised in PAGINATION_STRINGS or overridable via props (ariaLabel, prevLabel, nextLabel), but the compact "Page X of Y" summary is hardcoded English with no override hook. On a 14-language site this becomes the one pagination label that silently stays English in the sub-lg layout. Worth routing it through PAGINATION_STRINGS as a template (or accepting it as a prop) for consistency with the rest of the component.

The link-vs-interactive mode is selected implicitly by whether basePath is set, and several props only make sense in one mode — hidden is interactive-only per its own doc comment, and currentPage/totalPages are effectively meaningless in interactive mode since the client rebuilds them at runtime. Nothing in the Props type signals which props pair with which mode, so it's easy to pass a combination that does nothing. Grouping the props by mode in the doc comments — or a discriminated mode prop — would make the two-mode design harder to misuse.

The prev/next chevron is authored four times in this template: a 3-way (link / interactive button / disabled span) branch each for prev and next in the numbers list, plus two more 2-way branches in the compact row. They differ only in direction, target page, and label, so it's easy for the variants to drift — e.g. someone fixing an a11y attribute on one and missing the other three. A small local renderChevron(direction, enabled, hrefOrRole, label) fragment would collapse most of this duplication.

Two notes on restoreFocus:

1. offsetParent !== null is a leaky visibility probe — it works here only because the numbers/compact rows are toggled with display: none via media queries. If a future layout variant ever hides a row with visibility/opacity/clip instead, the desktop-vs-mobile focus pick would break silently. Worth a one-line comment pinning down the display:none-only assumption.
2. When the user pages to the last (or first) page via a chevron, that chevron has just become is-disabled — but it's still focusable (no disabled attribute, only aria-disabled + pointer-events: none), so focus is restored onto a dimmed, non-interactive control. Since data-nav-role matches before the .is-current fallback, that boundary case lands focus on the disabled chevron rather than the current page. Preferring the current-page button when the captured role resolves to a disabled control might feel less surprising.

applyPageSizeToUi re-implements PerPageSelector's own selection logic — the tb-pagination__per-page-option--selected class toggle, aria-pressed, label text, and the data-per-page dataset are all also owned by setupPerPage inside the component. So two files now have to agree on PerPageSelector's private class names and DOM contract, which cuts against the otherwise-clean black-box boundary (events + data attributes) the shared component establishes. Exposing a small helper like setPerPageValue(root, n) from the component would keep that markup owned in exactly one place.